@fluentui/keyboard-key

What is @fluentui/keyboard-key?

@fluentui/keyboard-key is a utility package that provides constants and helper functions for handling keyboard events in a consistent manner. It is particularly useful for managing keyboard interactions in web applications, ensuring that key codes are handled correctly across different browsers and platforms.

What are @fluentui/keyboard-key's main functionalities?

Key Code Constants

The package provides constants for common key codes, making it easier to handle keyboard events without having to remember the numeric key codes.

const { EnterKey, EscapeKey } = require('@fluentui/keyboard-key');
console.log(EnterKey); // Outputs: 13
console.log(EscapeKey); // Outputs: 27

Key Code Mapping

The package includes helper functions like `getCode` and `getKey` to map between key names and key codes, simplifying the process of working with keyboard events.

const { getCode, getKey } = require('@fluentui/keyboard-key');
console.log(getCode('Enter')); // Outputs: 13
console.log(getKey(13)); // Outputs: 'Enter'

Cross-Browser Compatibility

The package ensures that keyboard events are handled consistently across different browsers by providing utility functions like `isKey` to check if a specific key was pressed.

const { isKey } = require('@fluentui/keyboard-key');
const event = new KeyboardEvent('keydown', { keyCode: 13 });
console.log(isKey(event, 'Enter')); // Outputs: true

Other packages similar to @fluentui/keyboard-key

keycode

The 'keycode' package provides a simple API for converting between key names and key codes. It is similar to @fluentui/keyboard-key in that it helps manage keyboard events, but it is more lightweight and does not include as many utility functions.

mousetrap

The 'mousetrap' package is a library for handling keyboard shortcuts in web applications. While it offers more advanced features for binding and managing keyboard shortcuts, it does not provide the same level of key code constants and mappings as @fluentui/keyboard-key.

hotkeys-js

The 'hotkeys-js' package is another library for managing keyboard shortcuts. It is more focused on binding and handling complex keyboard shortcuts, whereas @fluentui/keyboard-key is more about providing key code constants and utility functions.

README

@fluentui/keyboard-key

A simple utility for determining the KeyboardEvent.key property from a keyboard event.

• Install
• Usage
  • getKey()
  • getCode()
• Why?
• Locale Caveat

Install

yarn add keyboard-key

# or

npm install keyboard-key

Usage

getKey()

Get the key property value from an event.

document.addEventListener('keydown', event => {
  const key = keyboardKey.getKey(event);

  switch (key) {
    case 'Escape':
      // handle escape key
      break;
    default:
      break;
  }
});

See MDN or the source for a full list of key values.

getCode()

You can also get the normalized keyCode from an event. @fluentui/keyboard-key includes a hash of key names to keyCodes for easy comparisons:

document.addEventListener('keydown', event => {
  const code = getCode(event);

  switch (code) {
    case keyboardKey.Escape: // 27
      // handle escape key
      break;
    default:
      break;
  }
});

Why?

Most previous key identifying KeyboardEvent properties have been pressed have been deprecated in favor of Keyboard.key.

:-1: KeyboardEvent.char :-1: KeyboardEvent.charCode :-1: KeyboardEvent.keyCode :-1: KeyboardEvent.keyIdentifier :-1: KeyboardEvent.keyLocation :-1: KeyboardEvent.which

:+1: KeyboardEvent.key

Unfortunately, KeyboardEvent.key does not yet have full browser support. Leaving the browsers without a reliable property for identifying keyboard event keys.

Locale Caveat

This utility interprets use of the shift key when inferring event key values. Example, an event describing shift+/ would result in a key value of ?. This logic assumes an en-US locale keyboard layout. This will not work if you are using a different locale such as a German layout where / is shift+7.